## -*- mode: html; coding: utf-8; -*-

## This file is part of CDS Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 CERN.
##
## CDS Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## CDS Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDS Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

<!-- WebDoc-Page-Title: BibKnowledge API -->

<protect>
<pre>

Adding/deleting knowledge bases:

def add_kb(kb_name="Untitled", kb_type=None):
    """
    Adds a new kb in database, and returns its id
    The name of the kb will be 'Untitled#' such that it is unique.
    @param kb_name the name of the kb
    @param kb_type the type of the kb, incl 'taxonomy' and 'dynamic'.
                   None for typical (leftside-rightside).
    @return the id of the newly created kb
    """

def delete_kb(kb_name):
    """
    Deletes given kb from database
    @param kb_name knowledge base name
    """

Mappings:

def get_kb_mappings(kb_name="", key="", value="", match_type="s"):
    """Get mappings from kb kb_name. If key given, give only those with
       left side (mapFrom) = key. If value given, give only those with
       right side (mapTo) = value.
       @param kb_name the name of the kb
       @param key include only lines matching this on left side in the results
       @param value include only lines matching this on right side in the results
       @param match_type s = substring match, e = exact match
    """

def add_kb_mapping(kb_name, key, value=""):
    """
    Adds a new mapping to given kb

    @param kb_name the name of the kb where to insert the new value
    @param key the key of the mapping
    @param value the value of the mapping
    """

Using:

def get_kba_values(kb_name, searchname="", searchtype="s"):
    """
    Returns an array of values "authority file" type = just values.
    @param kb_name name of kb
    @param searchname get these values, according to searchtype
    @param searchtype s=substring, e=exact
    """
    return bibknowledge_dblayer.get_kba_values(kb_name, searchname, searchtype)

def get_kbr_keys(kb_name, searchkey="", searchvalue="", searchtype='s'):
    """
    Returns an array of keys.
    @param kb_name the name of the knowledge base
    @param searchkey search using this key
    @param searchvalue search using this value
    @param searchtype s = substring, e=exact
    """


def get_kbr_values(kb_name, searchkey="", searchvalue="", searchtype='s'):
    """
    Returns an array of keys.
       @param kb_name the name of the knowledge base
       @param searchkey search using this key
       @param searchvalue search using this value
       @param searchtype s = substring, e=exact
   """

def get_kbr_items(kb_name, searchkey="", searchvalue="", searchtype='s'):
    """
    Returns a list of dictionaries that match the search.
    @param kb_name the name of the knowledge base
    @param searchkey search using this key
    @param searchvalue search using this value
    @param searchtype s = substring, e=exact
    @return a list of dictionaries [{'key'=>x, 'value'=>y},..]
    """

def get_kbd_values(kbname, searchwith=""):
    """
    To be used by bibedit. Returns a list of values based on a dynamic kb.
    @param kbname name of the knowledge base
    @param searchwith a term to search with
    """

def get_kbd_values_for_bibedit(tag, collection="", searchwith=""):
    """
    A specific convenience method: based on a tag and collection, create a temporary dynamic knowledge base
    a return its values.
    Note: the performace of this function is ok compared to a plain
    perform req search / get most popular fields -pair. The overhead is about 5% with large record sets.
    @param tag the tag like 100__a
    @param collection collection id
    @param searchwith the string to search. If empty, match all.
    """


def get_kbt_items(taxonomyfilename, templatefilename, searchwith=""):
    """
    Get items from taxonomy file using a templatefile. If searchwith is defined,
    return only items that match with it.
    @param taxonomyfilename full path+name of the RDF file
    @param templatefile full path+name of the XSLT file
    @param searchwith a term to search with
    """

</pre>
</protect>
